mudbox::Store< type > Class Template Reference

#include <array.h>

Inheritance diagram for mudbox::Store< type >:

Detailed Description

template<typename type>
class mudbox::Store< type >

Simple array class.

This class represents a simple array and should be used in all circumstances instead of plain C-style arrays. The class is templated, so that you can use to instantiate arrays of any type.

Its advantages of Store arrays include:

when the object is deleted, the associated data is deleted automatically. This means that if the Store instance was created on the heap, or it is a member variable of another class, then you don't have to bother freeing the memory, reducing the chance of a memory leak.

Additional functionality, such as expandability, sorting, and removing specified elements.

Easy to serialize.

The mudbox kernel can examine the list of all Store arrays in the memory at any time, which is helpful for diagnosing high memory footprint problems, as well as memory leaks.

Typical usage:

Typically, you create an empty Store instance, and then set the number of items (if you know it) by calling SetItemCount(). Alternatively, you can add elements into the array one by one, using the Add() function. If the elements of the array are class instances, their constructors and destructors can optionally be called when the array space is allocated and deallocated. (You must call the right methods.) For this reason, any class from which you will create an array should have a constructor that takes no arguments.

When the array is extended (for example when new elements are added by calling the Add() function), the existing array elements will be copied to the new location with the "=" operator of the element class. For this reason, you should ensure that this operator will work correctly, especially in cases where your class contains pointers. (If you have no "-" operator defined in the data class, it will just do a direct memory copy.)

A Store instance sometimes has more memory allocated than needed by the number of elements in the array. See the Optimize() function for more details.

Note: If you use the "=" operator to copy one entire Store array to another, the original array is left empty. (This is a speed optimization.) If you want to do a deep copy of the contents of the Store array, you should instead use the Clone() function as follows:

    Store<int> a;
    a = b.Clone();


Public Member Functions
	Store (const char *sName="unknown")
	Creates an empty array.
	Store (unsigned int iSize, const char *sName)
	Creates an array with space for some elements already allocated.
	Store (const type pArray, int iSize, const char sName="unknown")
	Creates an array and populates it will information copied from another array.
	Store (bool bNoObjects, const char *sName)
	Creates an empty array, allowing you to specify if elements have constructors or destructors that need to be called.
	Store (const Store &s)
	Creates an array from another one. The other array becomes empty after the operation.
	~Store (void)
	Destroys the contents of the array and deallocate its memory.
bool	Copy (Store &s) const
	Copies the contents of another array into this one, duplicating all data. Returns true if successful.
Store	Clone (void) const
	Returns a copy of this array. The returned copy will have a duplicate of all data in the original.
void	Clone (Store &s) const
	Copies the contents of another array into this one, duplicating all data.
void	Clear (bool bDestruct=false)
	Clears the array and deallocates its memory.
bool	SetItemCount (unsigned int iSize, bool bKeepContent=false)
	Sets the logical size of the array. Returns true if successful.
bool	Allocate (unsigned int iSize, bool bKeepContent=false)
	Preallocates memory for the an array, without changing the array's logical size. Returns true if successful.
bool	Extend (unsigned int iIndex)
	Extends the logical size of the array. Returns true if successful.
bool	Extend (int iIndex)
	Extends the logical size of the array. Returns true if successful.
void	RemoveTail (int iItemCount=1)
	Removes the final items from the array.
void	Fill (type cPattern)
	Fills the array with a specified element.
unsigned int	Add (const type &e)
	Adds a new item to the array, increasing the array size by 1. The index of the added element is returned.
unsigned int	Add (type &e)
	Adds a new item to the array, increasing the array size by 1. The index of the added element is returned.
Store &	operator= (const Store &s)
	Transfers the contents of another array to this one, leaving the original array empty.
void	GetFrom (Store &s)
	Transfers the contents of another array to this one, leaving the original array empty.
const type &	operator[] (unsigned int iIndex) const
	Returns an indexed item from the array.
type &	operator[] (unsigned int iIndex)
	Returns an indexed item from the array.
const type &	operator[] (int iIndex) const
	Returns an indexed item from the array.
type &	operator[] (int iIndex)
	Returns an indexed item from the array.
type *	operator+ (unsigned int iIndex)
	Returns a pointer to an item in the array. THIS FUNCTION IS UNSAFE.
type *	operator+ (int iIndex)
	Returns a pointer to an item in the array. THIS FUNCTION IS UNSAFE.
bool	IsEmpty (void) const
	Returns true if the array has no items.
	operator bool (void) const
	Allows you to use the array as a boolean in if statements. Evaluates to true if the array is not empty.
bool	operator! (void) const
	Evaluates to true if the array contains no items.
void	SetBuffer (type *pData, unsigned int iSize=0)
	Makes a Store array from a regular C or C++ array.
void	Serialize (class Stream &s)
	Serializes the the array and its contents from/to a stream.
void	Sort (void)
	Sorts the items in the array.
type *	Find (type a)
	Returns a pointer to the item in the array with a particular value. The array must be sorted before using this call.
type *	Find (type *a)
	Returns a pointer to the item in the array with a particular value. The array must be sorted before using this call.
unsigned int	Remove (const type &e)
	Remove every occurrence of a specified item from the array. Returns the number of removed items.
void	Remove (unsigned int iIndex)
	Removes the item at the specified index from the array.
unsigned int	RemoveDuplicates (void)
	Removes duplicated items from the array after sorting it.
unsigned int	ItemCount (void) const
	Returns the number of items in the array.
type &	Last (void)
	Returns the last item in the array, or 0 if the array is empty.
void	Optimize (void)
	Reduces the allocated memory size to match the size of the current elements in the array.
Public Attributes
unsigned int	m_iSize
Static Protected Member Functions
int	Compare (const void a, const void b)

Constructor & Destructor Documentation

template<typename type>
mudbox::Store< type >::Store	(	const char *	sName = `"unknown"`	)	`[inline]`

Creates an empty array.

Parameters:

sName

[in] A name for the array (optional). Displayed in the log only.

00307           : Array<type>( sName ) { m_iSize = 0; };

template<typename type>
mudbox::Store< type >::Store	(	unsigned int	iSize,
		const char *	sName
	)	`[inline]`

Creates an array with space for some elements already allocated.

The content of the array is undefined. (That is, constructors are not called. To create an array where constructors and destructors are called automatically, use this call:

           Store<myType> myInstance(false);

Parameters:

iSize	[in] The number of elements to allocate initially.
sName	[in] A name for the array (optional). Displayed in the log only.

00320           : Array<type>( sName, iSize ) { m_iSize = iSize; };

template<typename type>
mudbox::Store< type >::Store	(	const type *	pArray,
		int	iSize,
		const char *	sName = `"unknown"`
	)	`[inline]`

Creates an array and populates it will information copied from another array.

Note that the information from the source array is copied over using memcpy. It is the caller's responsibility to check that the array being copied from contains enough values to copy before calling this constructor.

Parameters:

pArray	[in] The array from which to copy elements
iSize	[in] The number of elements to copy over
sName	[in] A name for the array (optional). Displayed in the log only.

00331           : Array<type>( sName, pArray, iSize ) { m_iSize = iSize; };

template<typename type>
mudbox::Store< type >::Store	(	bool	bNoObjects,
		const char *	sName
	)	`[inline]`

Creates an empty array, allowing you to specify if elements have constructors or destructors that need to be called.

Parameters:

bNoObjects	[in] if true, constructors and destructors will not be called on the array objects.
sName	[in] A name for the array (optional). Displayed in the log only.

00337           : Array<type>( sName, bNoObjects ) { m_iSize = 0; };

template<typename type>
mudbox::Store< type >::Store	(	const Store< type > &	s	)	`[inline]`

Creates an array from another one. The other array becomes empty after the operation.

Parameters:

s	[in] The array whose contents will be transferred to this one

00342           : Array<type>( s.m_sName, s ) { m_iSize = s.m_iSize; s.m_iSize = 0; };

template<typename type>
mudbox::Store< type >::~Store	(	void		)	`[inline]`

Destroys the contents of the array and deallocate its memory.

00345 { Clear( !Array<type>::m_bData ); };

Member Function Documentation

template<typename type>
bool mudbox::Store< type >::Copy	(	Store< type > &	s	)	const `[inline]`

Copies the contents of another array into this one, duplicating all data. Returns true if successful.

Parameters:

s	[in] The array to be duplicated

00350                 { s.m_iSize = m_iSize; return Array<type>::Copy( s ); };

template<typename type>
Store mudbox::Store< type >::Clone	(	void		)	const `[inline]`

Returns a copy of this array. The returned copy will have a duplicate of all data in the original.

Reimplemented from mudbox::Array< type >.

00353 { Store s; s.SetItemCount( m_iSize ); Copy( s ); return s; };

template<typename type>
void mudbox::Store< type >::Clone	(	Store< type > &	s	)	const `[inline]`

Copies the contents of another array into this one, duplicating all data.

Parameters:

s	[in] The array to be duplicated

00358                 { s.SetItemCount( m_iSize ); Copy( s ); };

template<typename type>
void mudbox::Store< type >::Clear	(	bool	bDestruct = `false`	)	`[inline]`

Clears the array and deallocates its memory.

Parameters:

bDestruct

[in] If true, the destructor will be called for each element.

Reimplemented from mudbox::Array< type >.

00363           { Array<type>::Clear( bDestruct ); m_iSize = 0; };

template<typename type>
bool mudbox::Store< type >::SetItemCount	(	unsigned int	iSize,
		bool	bKeepContent = `false`
	)	`[inline]`

Sets the logical size of the array. Returns true if successful.

If the new size is smaller than the current size, items at the end of the array will be discarded. If the new size is larger, then a new memory block will be allocated. In this case, the existing items will only be copied to the new block only if bKeepContent is set to true.

Parameters:

iSize	[in] The new size of the array
bKeepContent	[in] if true, the original array contents will be preserved when the array size is increased.

00374     { 
00375         if ( iSize <= m_iSize )
00376         {
00377             m_iSize = iSize;
00378             return true;
00379         };
00380         if ( !bKeepContent ) 
00381             Clear(); 
00382         if ( Array<type>::Alloc( iSize ) ) 
00383         { 
00384             m_iSize = iSize; 
00385             return true; 
00386         };
00387         return false;
00388     };

template<typename type>
bool mudbox::Store< type >::Allocate	(	unsigned int	iSize,
		bool	bKeepContent = `false`
	)	`[inline]`

Preallocates memory for the an array, without changing the array's logical size. Returns true if successful.

This method can be used to increase efficiency when an array is expected to grow by a large number of small steps. For example, if you expect to add 50 items to an array one at a time, you can call Allocate() first to allocate the required space. This will prevent the need for frequent reallocation.

Parameters:

iSize	[in] The new size for the array
bKeepContent	[in] if true, the array contents will be preserved. Otherwise they will be discarded.

00398           { if ( !bKeepContent ) Clear(); return Array<type>::Alloc( iSize ); };

template<typename type>
bool mudbox::Store< type >::Extend	(	unsigned int	iIndex	)	`[inline]`

Extends the logical size of the array. Returns true if successful.

If the specified size is not larger than the current array, nothing will happen. Otherwise the logical size of the array will be extended to one more than the specified index. New memory will be allocated as necessary to hold the new items. Returns true if successful.

Parameters:

iIndex

[in] The array index to extend to. For example, if you specify 7, the new array will contain 8 elements (indexed 0 to 7).

Reimplemented from mudbox::Array< type >.

00408     { 
00409         if ( Array<type>::Extend( iIndex ) )
00410         {
00411             m_iSize = Max( m_iSize, iIndex+1 );
00412             return true;
00413         };
00414         return false;
00415     };

template<typename type>
bool mudbox::Store< type >::Extend	(	int	iIndex	)	`[inline]`

Extends the logical size of the array. Returns true if successful.

Parameters:

iIndex

[in] The array index to extend to. For example, if you specify 7, the new array will contain 8 elements (indexed 0 to 7).

00424           { return Extend( (unsigned int)iIndex ); };

template<typename type>
void mudbox::Store< type >::RemoveTail	(	int	iItemCount = `1`	)	`[inline]`

Removes the final items from the array.

Parameters:

iItemCount

[in] The number if items to remove from the end of the array

00429           { SetItemCount( ItemCount()-iItemCount ); };

template<typename type>
void mudbox::Store< type >::Fill	(	type	cPattern	)	`[inline]`

Fills the array with a specified element.

Parameters:

cPattern

[in] The value to which every item in the array will be set

00434           { for ( unsigned int i = 0; i < m_iSize; i++ ) operator[](i) = cPattern; };

template<typename type>
unsigned int mudbox::Store< type >::Add	(	const type &	e	)	`[inline]`

Adds a new item to the array, increasing the array size by 1. The index of the added element is returned.

If you plan to add a number of objects using this method, you can improve efficiency by preallocating all the space you will need using the Allocate() method.

Parameters:

e	[in] The element to be added to the end of the array

00442           { if( Array<type>::Extend( m_iSize ) ) { Array<type>::operator[]( m_iSize ) = e; return m_iSize++; } else return 0xffffffff; };

template<typename type>
unsigned int mudbox::Store< type >::Add	(	type &	e	)	`[inline]`

Adds a new item to the array, increasing the array size by 1. The index of the added element is returned.

If you plan to add a number of objects using this method, you can improve efficiency by preallocating all the space you will need using the Allocate() method.

Parameters:

e	[in] The element to be added to the end of the array

00450           { if( Array<type>::Extend( m_iSize ) ) { Array<type>::operator[]( m_iSize ) = e; return m_iSize++; } else return 0xffffffff; };

template<typename type>
Store& mudbox::Store< type >::operator=	(	const Store< type > &	s	)	`[inline]`

Transfers the contents of another array to this one, leaving the original array empty.

If you want to copy the contents of the source array (instead of transferring it), use the Copy() or Clone() functions.

00455 { m_iSize = s.m_iSize; s.m_iSize = 0; Array<type>::operator =( s ); return *this; };

template<typename type>
void mudbox::Store< type >::GetFrom	(	Store< type > &	s	)	`[inline]`

Transfers the contents of another array to this one, leaving the original array empty.

If you want to copy the contents of the source array (instead of transferring it), use the Copy() or Clone() functions.

Parameters:

s	[in] The array whose contents are to be transferred to this one

00462           { m_iSize = s.m_iSize; Array<type>::operator =( s ); };

template<typename type>
const type& mudbox::Store< type >::operator[]	(	unsigned int	iIndex	)	const `[inline]`

Returns an indexed item from the array.

Reimplemented from mudbox::Array< type >.

00465 { return Array<type>::m_pArray[iIndex]; };

template<typename type>
type& mudbox::Store< type >::operator[]	(	unsigned int	iIndex	)	`[inline]`

Returns an indexed item from the array.

Reimplemented from mudbox::Array< type >.

00468 { MB_ASSERT( iIndex < m_iSize ); return Array<type>::m_pArray[iIndex]; };

template<typename type>
const type& mudbox::Store< type >::operator[]	(	int	iIndex	)	const `[inline]`

Returns an indexed item from the array.

00471 { return operator[]( (unsigned int)iIndex ); };

template<typename type>
type& mudbox::Store< type >::operator[]	(	int	iIndex	)	`[inline]`

Returns an indexed item from the array.

Reimplemented from mudbox::Array< type >.

00474 { return operator[]( (unsigned int)iIndex ); };

template<typename type>
type* mudbox::Store< type >::operator+	(	unsigned int	iIndex	)	`[inline]`

Returns a pointer to an item in the array. THIS FUNCTION IS UNSAFE.

This method allows you to access the address of an array element. However, since many basic array operations can change the memory location of items in the array, this pointer should only be referenced immediately, and never kept around.

Reimplemented from mudbox::Array< type >.

00481 { return &operator[]( iIndex ); };

template<typename type>
type* mudbox::Store< type >::operator+	(	int	iIndex	)	`[inline]`

Returns a pointer to an item in the array. THIS FUNCTION IS UNSAFE.

Reimplemented from mudbox::Array< type >.

00488 { return &operator[]( iIndex ); };

template<typename type>
bool mudbox::Store< type >::IsEmpty	(	void		)	const `[inline]`

Returns true if the array has no items.

00491 { return ItemCount() == 0; };

template<typename type>
mudbox::Store< type >::operator bool	(	void		)	const `[inline]`

Allows you to use the array as a boolean in if statements. Evaluates to true if the array is not empty.

00494 { return !IsEmpty(); };

template<typename type>
bool mudbox::Store< type >::operator!	(	void		)	const `[inline]`

Evaluates to true if the array contains no items.

00497 { return IsEmpty(); };

template<typename type>
void mudbox::Store< type >::SetBuffer	(	type *	pData,
		unsigned int	iSize = `0`
	)	`[inline]`

Makes a Store array from a regular C or C++ array.

This method takes a pointer to a block of memory that contains a C-style array of elements of the appropriate type, and makes that into a Mudbox array object. Once this is called, the Store item will control the memory block, and extend or deallocate it as needed, as part of its own methods and destructor.

It is the responsibility of the caller to ensure that the source array is at least as big as the specified size.

00508 { m_iSize = Array<type>::m_iSize = iSize; Array<type>::m_pArray = pData; };

template<typename type>
void mudbox::Store< type >::Serialize	(	class Stream &	s	)

Serializes the the array and its contents from/to a stream.

Parameters:

s	[in] The stream from/to which to read/write the array

00290 {
00291     if ( !s.IsStoring() )
00292         SetItemCount( s.ReadInt() );
00293     else
00294         s << m_iSize;
00295     for ( unsigned int i = 0; i < m_iSize; i++ )
00296         s == operator[]( i );
00297 };

template<typename type>
void mudbox::Store< type >::Sort	(	void		)	`[inline]`

Sorts the items in the array.

This method will sort all the items in the array from least to greatest. If the array is of a non-numeric or non-string type, this method determines the relative ordering of items using the subtraction ("-") operator. In order to use this method, you must ensure that the subtraction operator is defined for the data type stored in this array, with these properties:

if A is less than B, then A-B must return a negative integer

if A is greater than B, then A-B must return a positive integer

if A is equivalent to B, then A-B must return 0

00527 { QuickSort( Array<type>::m_pArray, m_iSize, sizeof(type), Compare ); };

template<typename type>
type* mudbox::Store< type >::Find	(	type	a	)	`[inline]`

Returns a pointer to the item in the array with a particular value. The array must be sorted before using this call.

This method uses a binary search to return a pointer to an element in the array with the specified value. If the value is not found, then NULL is returned. Before this method can be called, the array must be sorted (by calling the Sort() method).

Note: The pointer returned by this function should not be kept for later use, as the contents of an array can move around in memory as items are added and removed. It should only be used immediately.

Parameters:

a	[in] The value to search for in the array

00539           { return (type *) bsearch( &a, Array<type>::m_pArray, m_iSize, sizeof(type), Compare ); };

template<typename type>
type* mudbox::Store< type >::Find	(	type *	a	)	`[inline]`

Returns a pointer to the item in the array with a particular value. The array must be sorted before using this call.

00549 { return (type *) bsearch( a, Array<type>::m_pArray, m_iSize, sizeof(type), Compare ); };

template<typename type>
unsigned int mudbox::Store< type >::Remove	(	const type &	e	)	`[inline]`

Remove every occurrence of a specified item from the array. Returns the number of removed items.

Parameters:

e	[in] the item to remove from the array

00555     {
00556         unsigned int j = 0, i = 0;
00557         while ( i < ItemCount() )
00558         {
00559             if ( operator[]( i ) != e )
00560                 operator[]( j++ ) = operator[]( i );
00561             i++;
00562         };
00563         SetItemCount( j );
00564         return i-j;
00565     };

template<typename type>
void mudbox::Store< type >::Remove	(	unsigned int	iIndex	)	`[inline]`

Removes the item at the specified index from the array.

Parameters:

iIndex

[in] index of the item to be removed

00571     {
00572         while ( iIndex+1 < ItemCount( ) )
00573         {
00574             operator[]( iIndex ) = operator[]( iIndex+1 );
00575             iIndex++;
00576         };
00577         SetItemCount( Min(iIndex,ItemCount()-1) );
00578     };

template<typename type>
unsigned int mudbox::Store< type >::RemoveDuplicates	(	void		)	`[inline]`

Removes duplicated items from the array after sorting it.

See the Sort() method for information on what makes an array Sort-able. This method sorts the contents of the array, then goes through and removes any duplicate entries, leaving a list of unique items. It returns the number of items that were removed.

00587     {
00588         if ( ItemCount() == 0 )
00589             return 0;
00590         Sort();
00591         unsigned int j = 0;
00592         for ( unsigned int i = 0; i < ItemCount()-1; i++ )
00593         {
00594             if ( operator[]( i ) != operator[]( i+1 ) )
00595                 operator[]( j++ ) = operator[]( i );
00596         };
00597         operator[]( j++ ) = operator[]( ItemCount()-1 );
00598         unsigned iRemoved = ItemCount()-j;
00599         m_iSize = j;
00600         return iRemoved;
00601     };

template<typename type>
unsigned int mudbox::Store< type >::ItemCount	(	void		)	const `[inline]`

Returns the number of items in the array.

00604 { return m_iSize; };

template<typename type>
type& mudbox::Store< type >::Last	(	void		)	`[inline]`

Returns the last item in the array, or 0 if the array is empty.

00607 { if ( ItemCount() ) return operator []( ItemCount()-1 ); else throw new Error( "Store::LastItem called for an empty store" ); };

template<typename type>
void mudbox::Store< type >::Optimize	(	void		)	`[inline]`

Reduces the allocated memory size to match the size of the current elements in the array.

Arrays derived from Store automatically grow their memory as needed to accommodate the items that are added to them. For efficiency, when an array expands it allocates more memory than it immediately needs. This reduces the number of expensive memory allocations.

The Optimize methods allocates a new block of memory, precisely the size needed to hold the current contents of the array, then copies the array data to this new block before deleting the existing block. Use it to minimize the memory footprint of arrays that are unlikely to expand, but that you need to keep around.

00618 { Array<type>::Alloc( m_iSize ); };

template<typename type>
int mudbox::Store< type >::Compare	(	const void *	a,
		const void *	b
	)	`[inline, static, protected]`

00621 { return (int)(*((type *)a)-*((type *)b)); };

Member Data Documentation

template<typename type>
unsigned int mudbox::Store< type >::m_iSize `[mutable]`

Reimplemented from mudbox::Array< type >.

mudbox::Store< type > Class Template Reference

Detailed Description

template<typename type> class mudbox::Store< type >

Public Member Functions

Public Attributes

Static Protected Member Functions

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

template<typename type>
class mudbox::Store< type >